Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / cmds.fmt / tcl.man < prev next >

Wrap

Text File | 1991-12-05 | 25.8 KB | 595 lines

TCLSHELL UNKNOWN MANUAL SECTION TCLSHELL NNAAMMEE Tcl - Tcl interactive shell. SSYYNNOOPPSSIISS ttccll [[--qq]] [[[[--ff]] _s_c_r_i_p_t]]||[[--cc _c_o_m_m_a_n_d]] [[_a_r_g_s] DDEESSCCRRIIPPTTIIOONN ttccll [[--qq]] [[[[--ff]] _s_c_r_i_p_t]]||[[--cc _c_o_m_m_a_n_d]] [[_a_r_g_s] TTccll starts the interactive Tcl command interpreter. The Tcl shell provides an environment for writing, debugging and executing Tcl scripts. The functionality of the Tcl shell can also be obtained in any Tcl-based application. The ttccll command, issued without any arguments, invokes an interactive Tcl shell. If _s_c_r_i_p_t is specified, then the script is executed noninteractively with _a_r_g_s being supplied in the Tcl variable `aarrggvv'. If _c_o_m_m_a_n_d is supplied, then this command (or series of commands, separated by `;') is executed, with `aarrggvv' containing _a_r_g_s. The Tcl shell is intended as an environment for Tcl program development and execution. While it is not a full-featured interactive shell, it provides a comfortable environment for the interactive development of Tcl code. Note that the package library code described here overrides the uunnkknnoowwnn command provided as part of the standard Berkeley Tcl library facility, although Tcl source libraries coded to that standard can be loaded and used by Extended Tcl. IINNIITTIIAALLIIZZAATTIIOONN SSEEQQUUEENNCCEE The standard Tcl shell initialization consists of the fol- lowing steps: Search for a default file. The default file is a Tcl script that is executed to set important Tcl variables that govern startup, such as TTCCLLPPAATTHH. The Tcl default file is searched for using the following algorithm: The current Extended Tcl version, represented by $ver, is included in the default file naming to allow multi- ple Tcl versions to exists on a system. Note that the Extended Tcl version is the standard Tcl version number with an alphabetic character added to indicated the version of Extended Tcl. The iinnffooxx vveerrssiioonn command will return this version number. - An environment variable, TTCCLLDDEEFFAAUULLTT, is checked for. If present, it is used as the name of the default file. - A file, TTCCLLDDEEFFAAUULLTT, is looked for in the current Tcl 1 TCLSHELL UNKNOWN MANUAL SECTION TCLSHELL directory. - A global default file with is usually either //eettcc//ddeeffaauulltt//ttccll$$vveerr or //uussrr//llooccaall//lliibb//ttccllddeeffaauulltt$$vveerr. (Tcl may be com- piled to use a different directory on some sys- tems). First, TTccll executes the default file. This file nor- mally sets at least two Tcl variables: TTCCLLPPAATTHH, which contains a list of directories that contain tcl source files, and TTCCLLIINNIITT, the full pathname of the Tcl source file that performs Tcl initialization. Other site- specific variables may also be set in this file. Next, ttccll executes the initialization file specified by the Tcl variable TTCCLLIINNIITT. This is normally the TTccllIInniitt..TTccll file distributed with Tcl. This file defines the Tcl environment, including standard Tcl procs and variables. FFLLAAGGSS --qq Quick initialization flag. If this flag is set the only initialization step performed is to locate the Tcl default file and save its name in the Tcl variable TCLDEFAULT. The file is not evaluated nor is the TclInit.tcl file. This provides for a faster start up, but does not make any of the standard Tcl procedures and facilities available. --ff Take the next argument as a Tcl script to source rather than enter interactive mode. The --ff flag is optional. Normally the first argument that does not start with a `-' is taken as the script to execute unless the `-c' option is specified. All following arguments are passed to the script in aarrggvv, thus any other Tcl shell flags must precede this option. --cc Take the next argument as a Tcl command to execute. It may be series of commands to execute, separated by `;'. All following arguments are passed in aarrggvv, thus any other Tcl shell flags must precede this option. ---- Mark the end of the arguments to the Tcl shell. All arguments following this are passed in the Tcl variable aarrggvv. This is useful to pass arguments without attempting to execute a Tcl script. TTCCLLIINNIITT FFIILLEE The Tcl initialization file, normally _T_c_l_I_n_i_t._t_c_l in the main Tcl script directory, initializes the Tcl shell. It defines various Tcl procedures that are required to Tcl 2 TCLSHELL UNKNOWN MANUAL SECTION TCLSHELL implement loading of Tcl source from libraries via the pack- age libraries and autoload facilities. If the Tcl is invoked interactively, it will source a ._t_c_l_r_c in the user's home directory, if it exists. Tcl is viewed primarly as a programming language, not an interactive shell, so the ._t_c_l_r_c is intended for use for loading development utilities, not to support programs, which should not rely on the user's environment. VVAARRIIAABBLLEESS The following variables are set and/or used by the Tcl shell. aarrggvv A list containing the arguments passed in from the com- mand line, excluding arguments used by the Tcl shell. The first element is the first passed argument, not the program name. iinntteerraaccttiivveeSSeessssiioonn Set to 11 if Tcl shell is invoked interactively, or 00 if the Tcl shell is directly executing a script. nnooAAuuttooEExxeecc If this variable exists and has a value of 11, then the Tcl shell will not attempt to exec an non-existent com- mand as a shell command. pprrooggrraammNNaammee The name that the Tcl shell is executing as. All directory components are removed from the program name. ssccrriippttNNaammee The name of the script that the Tcl shell is executing if the script was invoked on the command line. TTCCLLDDEEFFAAUULLTT Name of the default file that was used to locate all other files used by the Tcl shell. TTCCLLEENNVV Array that contains information used internally by various Tcl procedures that are part of the Tcl shell. TTCCLLEENNVV((ttooppLLeevveellPPrroommppttHHooookk)) Contains code to run to generate the prompt used when interactively prompting for commands. The code in this hook will be evaluated and the result will be used for the prompt. TTCCLLEENNVV((ddoowwnnLLeevveellPPrroommppttHHooookk)) Contains code to run to generate the prompt used when Tcl 3 TCLSHELL UNKNOWN MANUAL SECTION TCLSHELL interactively prompting for continuation of an incom- plete command. The code in this hook will be evaluated and the result will be used for the prompt TTCCLLIINNIITT The name of the file that initializes, and does startup processing of, Tcl. TTCCLLPPAATTHH Path to search to locate Tcl scripts. Used by the llooaadd and ddeemmaanndd__llooaadd procedures. HHEELLPP FFAACCIILLIITTYY The help facility allows for display of help files extracted from the standard Tcl manual pages and Tcl scripts. Help files are structured in a multilevel directory tree of sub- jects and help files. The following commands and options are provided with the help package: hheellpp Help, without arguments, lists of all the top-level help subject directories and files. hheellpp _s_u_b_j_e_c_t_d_i_r Displays all of help files and lower level subject files (if any exist) under the directory _s_u_b_j_e_c_t_d_i_r. hheellpp _s_u_b_j_e_c_t_d_i_r/_h_e_l_p_f_i_l_e Display the specified help file. The help output is passed through a simple pager if output exceeds 23 lines, pausing waiting for a return to be entered. If any other character is entered, the output is ter- minated. hheellppccdd [[_s_u_b_j_e_c_t_d_i_r] Change the current subject directory, which is much like the Unix current directory. This directory can be changed with the hheellppccdd command. If _s_u_b_j_e_c_t_d_i_r is not specified, return to the top-level of the help tree. Help path names may also include ``..'' elements. hheellppppwwdd Displays the current help subject directory. hheellpp hheellpp || ?? Displays help on the help facility at any directory level. aapprrooppooss _p_a_t_t_e_r_n This command locates subjects by searching their one- line descriptions for a pattern. Apropos is useful when you can remember part of the name or description Tcl 4 TCLSHELL UNKNOWN MANUAL SECTION TCLSHELL of a command, and want to search through the one-line summaries for matching lines. Full regular expressions may be specified (see the rreeggeexxpp command). CCOOMMMMAANNDD RREESSUULLTTSS The string result of a command typed at the Tcl shell com- mand prompt is normally echoed back to the user. If an error occurs, then the string result is displayed, along with the error message. The error message will be preceded by the string ``Error:''. The sseett command is a special case. If the command is called to set a variable (i.e. with two arguments), then the result will not be echoed. If only one argument, the name of a variable, is supplied to sseett, then the result will be echoed. EEXXEECCUUTTIIOONN OOFF UUNNIIXX CCOOMMMMAANNDDSS If an unknown Tcl command is entered from the command line, then the Unix command path, specified in the environment variable PPAATTHH, will be searched for a command of the same name. If found, the command will be executed. This feature is provided to enhance the interactive environment for developing Tcl scripts. This is only supported from the com- mand line, not in script files or in procedures, to elim- inate confusion. The eexxeecc or ssyysstteemm command should be used to run Unix commands inside scripts. TTCCLL SSHHEELLLL PPRROOCCEEDDUURREESS The follow additional procedures are defined by the Tcl shell and may be generally useful: llooaadd _f_i_l_e Source a file, as with the source command, except search the TCLPATH for the file. sseeaarrcchhppaatthh _p_a_t_h _f_i_l_e Search all directories in the specified path, which is a Tcl list, for the specified file. Returns the full path name of the file, or an empty string if the file is not found. AAUUTTOOLLOOAADD aauuttoollooaadd _f_i_l_e _p_r_o_c_1 [.._p_r_o_c_N] The _a_u_t_o_l_o_a_d procedure, defined in TTccllIInniitt..ttccll, allows the Tcl programmer to name one or more procedures and the file they are defined in. After _a_u_t_o_l_o_a_d has been executed to inform Tcl of the presence of them, a subsequent attempt to execute one of the procedures will cause the corresponding file to be loaded transparently prior to executing the func- tion. For example, executing: Tcl 5 TCLSHELL UNKNOWN MANUAL SECTION TCLSHELL autoload showproc.tcl showproc showprocs tells Tcl to automatically load the file sshhoowwpprroocc..ttccll the first time in the current session that either _s_h_o_w_p_r_o_c or _s_h_o_w_p_r_o_c_s is executed. PPAACCKKAAGGEE LLIIBBRRAARRIIEESS Package libraries work like _a_u_t_o_l_o_a_d, except that a package library file can contain multiple independent Tcl packages. A package is a collection of related Tcl procedures. The package library file is just a regular Unix text file, editable with your favorite text editor, containing packages of Tcl source code. The package library must end in ..ttlliibb, an index file with the suffix ..ttnnddxx will be built corresponding to the package library. The start of a pack- age is delimited by: ##@@ppaacckkaaggee:: _p_a_c_k_a_g_e__n_a_m_e _p_r_o_c_1 [.._p_r_o_c_N] These lines must start in column one. Everything between the ppaacckkaaggee keyword and the next ppaacckkaaggee keyword, or the end of the file, becomes part of the named package. The speci- fied procedures, _p_r_o_c_1.._p_r_o_c_N, are the entry points of the package. When a command named in a package command is exe- cuted and detected as an unknown command, all code in the specified package will be sourced. This package should define all of the procedures named on the package line, define any support procedures required by the package and do any package-specific initialization. For example, in a package source file, the presence of the following line: ##@@ppaacckkaaggee:: ddiirreeccttoorryy__ssttaacckk ppuusshhdd ppooppdd ddiirrss says that the text lines following that line in the package file up to the next _p_a_c_k_a_g_e line or the end of the file is a package named ddiirreeccttoorryy__ssttaacckk and that an attempt to execute either _p_u_s_h_d, _p_o_p_d or _d_i_r_s when the routine is not already defined will cause the ddiirreeccttoorryy__ssttaacckk portion of the pack- age file to be loaded. PPAACCKKAAGGEE IINNDDEEXX FFIILLEESS A package library file has associated with it an index file called a ..ttnnddxx file. The ..ttnnddxx file contains the names of the packages in the ..ttlliibb file, their addresses and lengths within the ..ttlliibb file and the functions that are to cause the different packages to be autoloaded when an attempt is made to execute them. The first time Tcl tries to execute a procedure where the Tcl 6 TCLSHELL UNKNOWN MANUAL SECTION TCLSHELL procedure doesn't exist and isn't an autoload, Tcl will search along TTCCLLPPAATTHH looking for any files ending in ..ttlliibb. For each one it finds, it checks to see if there is a corresponding file in the same directory ending in ..ttnnddxx. If the ..ttnnddxx file doesn't exist, or if its date of last modification is older than that of the ..ttlliibb file, the ..ttnnddxx is automatically (re)generated if possible. If Tcl can't regenerate the file (most likely due to file or directory permission problems), an error occurs. Demand loading is also supported from indexes build by the mmkkiinnddeexx..ttccll program, supplied with standard Tcl. However, iinniitt..ttccll is not loaded. Note that the iinnffoo lliibbrraarryy command is not used to locate libraries by this shell; the TTCCLLPPAATTHH variable is set by the default file and is used to locate the libraries. PPAACCKKAAGGEE MMAANNAAGGEEMMEENNTT CCOOMMMMAANNDDSS Several commands are available for building and managing package libraries. If you are not building package libraries and are using the standard Tcl initialization file, they are all transparent. These commands are either defined or autoloaded by TTccllIInniitt..ttccll. aauuttoopprrooccss Lists the names of all known autoload and package library procedures. bbuuiillddppaacckkaaggeeiinnddeexx _l_i_b_f_i_l_e Build an index for a package library. The the _l_i_b_f_i_l_e name must end with the suffix ..ttlliibb. ddeemmaanndd__llooaadd _p_r_o_c_n_a_m_e Attempt to load the specified procedure, either as an autoload function or by loading the package containing the procedure. If the package indexes have not been loaded for all package libraries in TTCCLLPPAATTHH, they will be loaded. Out-of-date library indexes will be rebuilt if they are writable. The procedure returns 11 if the procedure was sucessfully loaded, or 00 if it was not. llooaaddlliibbiinnddeexx _l_i_b_f_i_l_e Load the package library index of the library file lliibb-- ffiillee (which must have the suffix ._t_l_i_b). Package library indexes along the TTCCLLPPAATTHH are loaded automati- cally on the first demand_load; this command is pro- vided to explicitly load libraries that are not in the path. If the index file (with a ._t_n_d_x suffix) does not exists or is out of date, it will be rebuilt if the user has directory permissions to create it. ppaacckkaaggeess Tcl 7 TCLSHELL UNKNOWN MANUAL SECTION TCLSHELL Returns a list of the names of all known packages. This section discusses the internal structure of the stan- dard Tcl initialization file and the facilities it imple- ments. This is intended primarily for developers who want to customize these facilities for their applications. AAuuttoollooaadd aanndd PPaacckkaaggee LLiibbrraarryy SSttrruuccttuurreess The package library index consists of an entry for each package in the library, where each entry is a call to the TTCCLLSSHH::ddeeffppkkgg procedure. Loading of the package index is done with the ssoouurrccee command. The _d_e_f_p_a_c_k_a_g_e routine ini- tializes elements of the TTCCLLEENNVV array which are used by ddeemmaanndd__llooaadd to locate and load a package. The bbuuiillddppaacckk-- aaggeeiinnddeexx procedure is contained in ppaacckkaaggeess..ttccll. The following elements of the TTCCLLEENNVV are used to implement the autoload and package library facility. TTCCLLEENNVV((PPRROOCC::_p_r_o_c_N_a_m_e)) Each procedure that is to be loaded by the ddeemmaanndd__llooaadd command has an entry in this array, indexed by the con- catenation of `PROC:' with the procedure name. If the entry is for a package, it is a list consisting `P' followed by the name of the package. The package name must be looked up in the TCLENV array to find the actual library file. If the entry is for an autoload procedure, it is a list consisting of 'F' followed by the name of the file to load. TTCCLLEENNVV((PPKKGG::_p_a_c_k_a_g_e_N_a_m_e)) Each package has an entry in the array indexed by the concatenation of `PKG:' and the name of the package. The entry is a list containing the full path to the library file, the byte offset in the file of the start of the package, and the length of the package. TTCCLLEENNVV((ppaacckkaaggeeIInnddeexxeessLLooaaddeedd)) A boolean that indicates if the package indexes have been loaded. They will not be loaded until the first call to ddeemmaanndd__llooaadd. TTCCLLEENNVV((iinnUUnnkknnoowwnn)) Indicates if the uunnkknnoowwnn command is currently being executed. It is used to detect recursion in situations where an unknown command is found during unknown com- mand processing. The following procedures are used to implement the internals of the autoload and package library facility, and are defined by TTccllIInniitt..ttccll: Tcl 8 TCLSHELL UNKNOWN MANUAL SECTION TCLSHELL TTCCLLSSHH::ddeeffppkkgg _p_k_g_n_a_m_e _l_i_b_f_i_l_e _o_f_f_s_e_t _l_e_n _p_r_o_c_1 [.._p_r_o_c_N] Define a package for the current interpreter. _P_k_g_n_a_m_e is the name of the package to define, _l_i_b_f_i_l_e is the full path to the library file. _o_f_f_s_e_t is the byte offset into the of the start of the package code; _l_e_n is the length of the package code, in bytes, and _p_r_o_c_1.._p_r_o_c_N are the entry point procedures defined by the package. This procedure is normally not called directly by the user or the user's script. The library index files consists of calls to this procedure to define every package in a library. TTCCLLSSHH::LLooaaddOOuusstteerrIInnddeexx ddiirr Load an index file, _d_i_r/ttccllIInnddeexx, of the type built by John Ousterhout's mmkkiinnddeexx..ttccll program (included with the standard Tcl distribution). This style of index defines procedure names and the files that contain them. It is a one-index-to-many-source-files struc- ture. All of the files pointed to by this must reside in _d_i_r. The procedures in these libraries will be defined as if the autoload command had been used. TTCCLLSSHH::LLooaaddPPaacckkaaggeeIInnddeexxeess This procedure searches the path defined by Tcl vari- able TTCCLLPPAATTHH and loads all of the indexes for all of the ._t_l_i_b package libraries in the path. If any of the indexes are older that their corresponding library file or do not exist, then they will be rebuilt if the user has write access to the directory. Also all Ousterhout-style indexes found along the path will be loaded. uunnkknnoowwnn This is the actual unknown command trap handler. It will first do a ddeemmaanndd__llooaadd, loading the uunnkknnoowwnn com- mand if it has been defined by aauuttoollooaadd, or by a pack- age library index. The library indexes will be be loaded if this is the first call to uunnkknnoowwnn. If the command is not found by ddeemmaanndd__llooaadd, the Unix path (in the environment variable PPAATTHH, will be searched for the command. If it is found, it will be executed via the ssyysstteemm command, providing full shell (sshh) command line expansion, with output going to standard out rather than being returned as the result of the command. This binary path search will only occur if this is an interactive session running at the top level (i.e., not in a procedure or a script). This behavior can be dis- abled with the nnooAAuuttooEExxeecc variable. Tcl 9